feat(pagination): expose page param on list-query tools#71
Merged
Conversation
The list-query MCP tools hit paginated backends (ListOptions{Page,Limit})
but exposed only `limit` (max 100) — any result past the first page was
unreachable, so a query matching >100 items silently dropped the tail with
no recourse but narrowing the window/filters.
Add a 1-based `page` param to every list tool that queries a Page-capable
endpoint and surfaces a `total`: query_incidents, query_changes,
query_incident_alerts, query_channels, query_members, query_teams. The
three that had no `limit` (channels/members/teams) gain both. Dedicated
by-ID lookups that return everything (incident_ids→list-by-ids,
person_ids→person/infos, team_ids→team/infos) stay unpaged; channel_ids is
a filter on the same paginated /channel/list, so it pages like any listing.
Fix the truncation signal for paged reads: `addTruncationHint` compared
`total > count` (this page's size), which was correct only on page 1 — on a
final partial page it falsely reported "truncated" and sent the agent
chasing an empty next page. New `addPageHint` accounts for the page offset
(seen = (page-1)*limit + count) and names the exact next page. Full-set /
by-ID responses keep `addTruncationHint`.
Shared `optionalPaging` helper centralizes the limit/page parse across the
six handlers; `PageDescription` mirrors `LimitDescription`. Wire-level tests
cover page reaching the backend as `p` (and default omitting it), the
channel_ids/person_ids path split, and the last-page truncation math.
Out of scope: list_similar_incidents (backend /incident/past-list has no
Page — top-N by design).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The list-query MCP tools hit paginated Flashduty backends (
ListOptions{Page, Limit}) but exposed onlylimit(max 100). Any result past the first page was unreachable — a query matching >100 items silently dropped the tail, with no recourse but narrowing the time window/filters. Thetruncated/hintmachinery even flagged the shortfall while offering no way to page.Fix
Add a 1-based
pageparam to every list tool that queries a Page-capable endpoint and surfaces atotal:query_incidentspagequery_changespagequery_incident_alertspage(applied per incident)query_channelslimit+pagequery_memberslimit+pagequery_teamslimit+pageDedicated by-ID lookups that return everything stay unpaged (
incident_ids→list-by-ids,person_ids→person/infos,team_ids→team/infos).channel_idsis a filter on the same paginated/change.../channel/list, so it pages like any listing.Truncation-signal correctness
addTruncationHintcomparedtotal > count(this page's size) — correct only on page 1. On a final partial page it falsely reportedtruncatedand sent the agent chasing an empty next page. NewaddPageHintaccounts for the page offset (seen = (page-1)*limit + count) and names the exact next page. Full-set / by-ID responses keepaddTruncationHint.change_idscorrectness/change/listhas no server-side id filter, soquery_changes(change_ids=…)filters one page client-side. It now reportstotal= found count and skips the page hint (feeding the filtered count with the window's unfiltered total intoaddPageHintwould mislead: "Showing 0 of 5000, request page:2").Consistency
Shared
optionalPaginghelper centralizes thelimit/pageparse across the six handlers (also removes a stray hardcoded20inquery_changes);PageDescriptionmirrorsLimitDescription.Out of scope
list_similar_incidents— backend/incident/past-listhas noPage(top-N by design).Tests
pagination_page_test.go: wire-level tests thatpagereaches the backend asp(and default omits it), thechannel_ids/person_idspath split, thechange_idsfound-count/no-hint behavior, and a table-drivenTestAddPageHintcovering the last-page math.go build,go vet, andgo test ./pkg/... ./internal/...all pass. (make lintfails locally on a golangci-lint↔go toolchain version mismatch, unrelated to this change.)